Status of the HTTP Responses

The HTTP response status code indicates the result of the operation, as per the convention described in RFC 7231. In case of error, the format of the response depends on the error type.

Status Codes of Correctly Completed Operations

When an operation is completed satisfactorily, the response body may contain more information on the result of the operation.

HTTP/1.1 200 OK

The operation was completed successfully. The body of the response can include more information on the result of the operation.

HTTP/1.1 201 Created

The operation for creating a new resource was complete correctly. The body of the response includes information on the resource created or the Location header contains the access URL to the resource.

HTTP/1.1 204 No content

The operation was completed successfully. No entity is obtained as a response and the body is empty.

Status Codes with the error Parameter in the HTTP WWW-Authenticate Header

When an authorization error occurs, an error code is obtained in the error parameter of the HTTP WWW-Authenticate header of the response, as described in [RFC 6750]. For example:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token"

Below is a list of the status codes that can appear in a WWW-Authenticate header, and the possible values of the error parameter in each case.

HTTP/1.1 400 Bad Request

  • invalid_request: The request could not be processed owing to incorrect syntax in the HTTP Authorization header, possibly because it is malformed or because there are more than one.

HTTP/1.1 401 Unauthorized

  • Without error code: The authentication conditions required were not met because the request did not include an HTTP Authorization header, or it was included but with an HTTP authentication scheme not recognized.

  • invalid_token: The authorization token is invalid or has expired. For OAuth tokens, the token expires after the number of seconds specified in the result of the Obtain a Token operation elapses (expires_in parameter). Furthermore, the authorization server considers valid the JWT tokens with issue times within either 10 minutes before or after the time of the server.

HTTP/1.1 403 Forbidden

  • insufficient_scope: The scopes to which the access token are associated are not sufficient for accessing the protected resource. The WWW-Authenticate header includes an additional scope parameter with the expected scope. An OAuth token is associated to the scopes specified in the obtain authorization or obtain access token operation, depending on the type of OAuth grant used for obtaining the token.

Status Codes with an Optional Description of the Error in the Response Body

For any other type of error, the response body usually contains a JSON data structure with the following parameters:

  • error: Error code.

  • error_description: Optional. Additional description of the error.

  • error_details: Optional. Additional details of the error. The format is a JSON object with subfields.

For example:

HTTP/1.1 400 Bad Request
{
"error": "NotSupportedException",
"error_description": "Cannot consume content type",
"error_details": { }
}

The possible values of the error parameter for the various status codes are described below.

HTTP/1.1 400 Bad Request

The syntax of the request is incorrect or the conditions required for completing the operation have not been met.

  • AccountAlreadyExistsException: The value of the unique attribute specified in the request as the explicit identifier of the user account is already assigned to another account.

  • AccountAttributeNotDefinedException: One of the attributes specified in the request is not defined in the identity domain or is not mapped to the user account.

  • AmbiguousSignIdentityTypeException and MultipleIdentitiesSelectedException: The labels requested from the signature provider for creating a digital signature identify more than one available signing identity.

  • BadRequestException: The request is incorrect.

  • BlockedDeviceException: The signature device for which the operation was requested has a process pending completion.

  • DeviceAlreadyExistsException: The signature device for which registration is requested already exists.

  • DeviceTypesNotExistsException: The type of signature device specified in the creation of the signing identity does not match any registered in the configuration.

  • EventNotFoundException: The queried event was not found.

  • InconsistentLinkedAccountIdException: An attempt was made to update the information on a linked account by specifying an external domain identifier (domain field) or the identifier of an external identity account_id field) that does not match those already associated to the linked account. Once the linked identity is created, these properties cannot be edited.

  • IncorrectDataToSignException: Error in the input data provided for signing. This entry must be coherent with the specified signing algorithm. The input data cannot be a "digest_value" when the signing algorithm is "rsa-pkcs1".Neither can the input data be "data" when the signing algorithm is something other than "rsa-pkcs1".

  • IncorrectSignatureAlgorithmException: The signing algorithm specified in the signature request is not supported.

  • IncorrectSignIdentitySelectorsException: The requested signing identity selector is incorrect or the associated identity does not exist.

  • InsufficientPasswordStrengthException: The password to be registered does not meet the strength requirements.

  • InvalidAttributeValueException: One of the attributes specified in the request has no value or has an unsupported format.

  • InvalidClientIdPrefixException: The prefix to be included in the identifier of an OAuth 2.0 client application has more than 64 characters or includes special characters.

  • InvalidClientMetadataException : Some of the OAuth 2.0 client application's attributes specified in the request are not valid.

  • InvalidClientTemplateIdException: There exists no OAuth 2.0 client application template with the identifier specified in the request.

  • InvalidCsrTemplateException: The template for generating the certification request specified in the creation of the signing identity request is incorrect.

  • InvalidExternalDomainNameException: The name of the external domain specified in the request body is invalid or the external domain is not federated to the user's domain.

  • InvalidFormatException: An invalid value was given to the search_count or search_limit parameter in an event query.

  • InvalidGrantException : When requesting an access token from an authorization server, invalid information was provided in the request.

  • InvalidKeyDataException: When the addition of a system cryptographic key was requested, an invalid cryptographic key algorithm was specified.

  • InvalidKeyGenerationParamsException: When the generation of a system cryptographic key was requested, the identifier of a nonexistent system key was provided in the property template.key_name.

  • InvalidKeyTemplateException: The template for generating the keys specified in the creation of the signing identity request is incorrect.

  • InvalidParameterException: An unrecognized parameter was provided in an event query.

  • InvalidParametersException: The value of one or more parameters specified in the request is not supported.

  • InvalidPkcs12Exception: The PKCS #12 and the password received for creating the identity are incorrect or cannot be used.

  • InvalidReferenceException: An invalid value was given to the search_ref (page reference) parameter in an event query.

  • InvalidQueryFilterException: The filter parameter specified in the request is malformed, includes an attribute not defined in the identity domain or is not mapped to the user accounts, or the attribute is not defined as unique.

  • InvalidRequestException: The syntax of the request is incorrect, or the value of one or more parameters specified in the request is not supported.

  • JsonParseException and JsonProcessingException: The request body is malformed.

  • JsonMappingException: A date in the wrong format was given to the from parameter or an incorrect value was given to the order field in an event query.

  • LinkedAccountAlreadyExistsException: The user account already has an identity linked to the external domain (domain field) and the identifier of the external identity (account_id field) specified.

  • MandatorySignatureException: The signature process has no signature definition defined.

  • ModelValidationException: The request is incorrect because some parameter required in the URL or the body is missing or because the content of the body is empty or incomplete.

  • MissingExternalAccountIdException: The request body does not include the identifier of the external identity in the federated identity domain (account_id field).

  • MissingUserIdAttributeException: The request body does not include the value of the attribute used to determine the explicit identifier of the user account.

  • MultipleAccountsForUniqueAttributeException: The value of a unique attribute specified in the request is already assigned to another user account.

  • MultipleValuesForUniqueAttributeException: A unique attribute specified in the request has multiple values.

  • NotSupportedException: The Content-type header of the request is not supported. The majority of the operations expect the application/json value in this header.

  • NotSupportedSignatureParametersException and UnexpectedSignerParametersTypeException: The parameters requested in the signature definition are incorrect.

  • NumberFormatException: An invalid value was given to the search_ref, timestamp or log_id parameter in an event query (one of the keys that make up the value of one of these parameters exceeds the largest whole number permitted).

  • PaginationLimitExceededException: An invalid value (less than 0 or greater than 100) was given to the search_limit (page size) parameter in an event query.

  • PublicKeyMismatchException: The public key of the certificate provided is not the public key of the signing identity.

  • SignaturePolicyNotFoundException: No signature policy was specified.

  • SignaturePolicyNotSupportedException: The signature policy requested is not supported.

  • TokenToRevokeNotIssuedToCallerException: A client application requested to revoke an access token that was not issued for it.

  • UnallowedRedirectUrisException: An attempt was made to assign a URI to an OAuth 2.0 client application that applications of that type cannot use.

  • UndefinedIdentityDomainException: The authorization token is associated to an undefined identity domain. If the token is a JWT token of a delegated server, the subfield of the token was not correctly defined (see Authorization for Using APIs for more details).

  • UnmatchingSignIdentityTypeException and UnsuitableDeviceForSignIdentityException: The labels of the signing identity requested to be created do not match any identity type established in the configuration.

  • UnregisteredClientApplicationException: The referenced client application is not registered in the TRIDENT.

  • UnselectableIdentityProviderException: TRIDENT could not resolve which Identity Provider to use.

  • UnsupportedSignIdentityCapabilityException: The signature identity specified is incompatible with the operation requested

HTTP/1.1 401 Unauthorized

The request does not include valid authentication credentials.

  • UserAuthenticationRequiredException: The access token is not associated to a user.

HTTP/1.1 403 Forbidden

The server does not authorize access to the resource, e.g., because the authorization type used is incorrect or does not provide sufficient permissions.

  • DisabledSignIdentityException: The signing identity is disabled.

  • InsufficientPermissionsException and PermissionsRequiredException: The permissions granted by the authorization token are not sufficient for accessing the protected resource. If a JWT token was used, the permissions of the token are fixed. See Authorization for Using APIs for more information.

  • InsufficientPermissionsForAttributeException: The permissions granted by the authorization token are not sufficient for obtaining one of the attributes requested in the request.

  • InvalidPrivilegeException and NoSuchPrivilegeException: The permissions granted by the authorization token are not sufficient for the operation execution.

  • LockedSignIdentityException: The server signing identity is locked.

  • NotAuthorizedException: The authorization token was not obtained with the adequate OAuth flow, or the identity domain was not specified or could not be deduced.

  • UserNotAuthorizedException: The authorization token must not be associated to a user or it is not associated to the same user as specified in the request.

  • UserDomainAccessRequiredException: Administrative authorization is required for access to the identity domain. If the call was authorized by an OAuth token, this error can occur if the token was issued by an authorization server not associated to any identity domain.

HTTP/1.1 404 Not Found

Resource not found.

  • AccountPasswordNotDefinedException : It is not defined in the identity domain how to evaluate the strength of a password with the name specified nor that of passwords with any name.

  • ClientNotFoundException: The OAuth 2.0 client application specified in the request does not exist.

  • DocumentNotFoundException and DocumentNotFoundRuntimeException: The document on which an operation was requested does not exist.

  • ItemNotFoundException and NotFoundException: The resource on which an operation was requested does not exist.

  • PasswordNotSetException: There is no password registered with this name for the user.

  • ProcessNotFoundException: The signature process of a document on which an operation was requested does not exist.

  • UnknownLinkedAccountException: The linked identity specified in the request does not belong to the user.

  • UnknownLogicalKeyException: The system key specified in the request does not exist.

  • UnknownUserAccountException: The user account specified in the request does not exist.

HTTP/1.1 405 Method Not Allowed

The HTTP method specified in the request is not sufficient for accessing the resource.

  • ClientWithoutSecretException : Attempt to renew the secret of an OAuth 2.0 client application that lacks it because it does not authenticate.

  • NotAllowedException: The server does not support the HTTP operations specified in the request.

HTTP/1.1 409 Conflict

The modification requested in the request cannot be applied given the current status of the resource.

  • InvalidStateException: The status of the resource does not allow performing the operation.

  • KeyAlreadyAddedException: An attempt was made to add a system cryptographic key with the same identifier as an existing key.

  • LogicalKeyInsertionConflictException: An attempt was made to add a cryptographic key out of sequence, i.e., with an incorrect reference to the previous cryptographic key associated to the same system key or by providing an empty reference when there are existing cryptographic keys associated to the system key.

HTTP/1.1 410 Gone

The resource does not and will not exist.

HTTP/1.1 415 Unsupported Media Type

The data sent to the server is not of the type required by the operation.

HTTP/1.1 422 Unprocessable Entity

The modification requested is correct but cannot be performed because it would leave the resource in an invalid status.

  • InconsistentUpdateRequestException: The changes cannot be applied simultaneously on the resource.

HTTP/1.1 500 Internal Server Error

Unexpected server error. In these cases, the TRIDENT's administrator must browse the log records to identify the problem.